<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
    
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    
  <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
    
  <meta name="author" content="Ian Brown">
    
  <meta name="GENERATOR" content="Mozilla/4.75 [en] (WinNT; U) [Netscape]">
  <title>RBNB V2.0 FAQ</title>
</head>
 <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#ff0000" alink="#000088">
  
<h1> RBNB V2.0 FAQ</h1>
 This document provides a list of Frequently Asked Questions and answers to
those questions for the RBNB V2.0 software. It also addresses differences 
between V1.x and V2.0 when the differences are likely to cause misunderstandings. 
<h2> Table of Contents</h2>
  
<blockquote><a href="#byteorder">How is byte order handled?</a>
 <br>
  <a href="#automatictimestamps">Where are automatic time-stamps generated?</a>
 <br>
  <a href="#ringbuffer">What is the ring buffer?</a>
 <br>
  <a href="#ringbufferconfig">How do I configure the the ring buffer?</a>
 <br>
  <a href="#archiving">When is data written to the archive?</a>
 <br>
  <a href="#loadinganarchive">How do I load an archive back into the server?</a>
 <br>
  <a href="#V2times">How do I set V2 timestamps?</a>
  </blockquote>
  
  <h2> <a name="byteorder"></a>
How is byte order handled?</h2>
 Normally, byte order is handled automatically by the RBNB system. The API 
automatically determines the source byte order and swaps bytes as needed to
ensure that the sink gets the data in the byte order it expects. For example,
arrays of primitives (shorts, floats, Java longs, etc.) in Java and C can
be put into the RBNB system and then retrieved by any other Java or C application.
So long as the source application has or can convert the data into such an
array,&nbsp; sink applications do not need to handle byte order. 
  <p>For a complete list of the primitive types supported by the RBNB system, 
see the <tt>ChannelMap.TYPE_xxx</tt> fields. </p>
  <p>When the source's byte order is significant and must be maintained (as 
with legacy applications), the data should be passed through the RBNB system 
in the form of an array of bytes using&nbsp; <tt>TYPE_INT8</tt>. This turns 
off the automatic byte order handling in the RBNB system and leaves the user
responsible for dealing with any byte order issues. Programs such as <tt>
rbnbPlot</tt> that expect to be informed of the data type are unable to display
such data. </p>
  <h2> <a name="automatictimestamps"></a>
Where are automatic time-stamps generated?</h2>
 Automatic time-stamps are generated by the client-side API. This is unlike 
V1.x, where the server generates automatic time-stamps.&nbsp; In a future 
V2 release, we may restore server-side automatic timestamps, as this provides 
a convenient way to synchronize multiple source clients.&nbsp; Keep in mind
that automatic timestamps are meant to be a convenient but approximate solution.&nbsp;
Use explicit PutTime methods to more precisely control the timestamps. 
  <h2> <a name="ringbuffer"></a>
What is the ring buffer?</h2>
 The Ring Buffered part of the "Ring Buffered Network Bus" refers to the way
that data is stored in the RBNB system. A ring buffer stores data in what
appears to be a seamless ring of slots, each slot holding one block (termed
a "frame") of data. At data arrives, it is placed in the next slot in the
ring, replacing any previous frame stored in the slot. Pointers are maintained
to the slot containing the oldest and newest data still stored in the ring
buffer. 
  <p>In V2.0, as with V1.x, the ring buffer actually consists of two main 
parts: </p>
  <ol>
 
    <li> An in-memory "cache", and</li>
  
    <li> A disk file "archive".</li>
 
  </ol>
 Unlike V1.x, where a single frame was the unit size for both adding and removing
objects from the cache and archive, V2.0 adds two new hierarchical objects
that increase the granularity of the ring buffer, while reducing the effort
required to maintain its integrity when new data replaces older data. These
two new objects are: 
  <ol>
 
    <li> FrameSets, which are the basic blocks of the cache, and</li>
  
    <li> FileSets, which are the basic blocks of the archive.</li>
 
  </ol>
 Frames (sent when a source flushes a ChannelMap) are added to the current 
active frameset as they arrive in the cache. Once the frameset reaches a
configurable size, it is closed and a new one is created. Framesets are added
to the current active fileset in the archive as they are closed by the cache.
Once the fileset reaches a configurable size, it is closed and a new one
is created. Closed framesets and filesets are read-only; no further frames
or framesets are added, nor are any removed. 
  <p>When the cache reaches its configured maximum size, a new frameset replaces 
the oldest frameset still in the cache. The oldest frameset is simply removed 
from the cache. Similarly, when the archive reaches its configured maximum 
size, new filesets replace the oldest fileset still in the archive. This is
done by simply deleting the fileset, which consists of a directory containing 
several files. </p>
  <h2> <a name="ringbufferconfig"></a>
How do I configure the the ring buffer?</h2>
 The desired sizes of the cache and archive in frames are set by the source 
application when creating the source handle via the simple API. The actual 
maximum sizes of the cache and archive may be adjusted to maintain efficient 
integral relationships between: 
  <ol>
 
    <li> Frameset size for the cache</li>
  
    <li> Maximum size of the cache (frameset size times number of framesets)</li>
  
    <li> Fileset size for the archive</li>
  
    <li> Maximum size of the archive (fileset size times number of filesets)</li>
 
  </ol>
 The simple API does not currently allow the user to directly set the number 
of framesets and filesets. Instead, the server starts with a default of 10,
and may adjust this to make sure that every frameset contains one or more
frames, and every fileset contains one or more framesets. 
  <h2> <a name="archiving"></a>
When is data written to the archive?</h2>
 Data is written to the archive whenever a frameset is closed. At that time, 
the contents of the frameset are written to the archive in the current fileset. 
  <p>This is similar to the asynchronous mode in V1.x and, as with that mode, 
there is the danger that frames added to the most current frameset may not
get written out to the archive if the server (or the host machine it is running
on) should crash. This vulnerability will be addressed in a future release. 
  </p>
  <h2> <a name="loadinganarchive"></a>
How do I load an archive back into the server?</h2>
 When the source application creates its source handle via the constructor 
or through the use of the SetRingBuffer method. In addition to the size of
the cache and the archive, there is a archive mode field which can take the
following values: 
  <ul>
 
    <li> None - no archive,</li>
  
    <li> Load - loads an existing archive read-only,</li>
  
    <li> Create - creates a new archive using the sizes specified, or</li>
  
    <li> Append - opens an existing archive and adjusts its size according
to the sizes provided.</li>
 
  </ul>
 When an archive is loaded, no new data can be added to it. When an archive 
is opened for append, then the archive size is adjusted to match the new desired
size as closely as possible. The frameset and fileset sizes are not changed. 
  <br>
&nbsp; 
  <h2> <a name="V2times"></a>
How do I set V2 timestamps?</h2>
 In V2 RBNB, timestamps are designed to be simple yet efficient.&nbsp; The 
timestamp(s) you specify with the PutTime methods remain the "current" time
that applies to subsequent PutData calls.&nbsp; Thus, for the simplest case,
you can set the time once for all data, as in: 
  <blockquote>PutTime <br>
BeginLoop 
    <blockquote>PutData</blockquote>
 EndLoop</blockquote>
 If you want to explicitly set the time for every PutData, then structure 
your code to pair the PutTime/PutData calls, as in: 
      <blockquote>BeginLoop 
        <blockquote>PutTime <br>
PutData</blockquote>
 EndLoop</blockquote>
  <br>
&nbsp; 
          </body>
          </html>
